.TH E1432_READ_RAW_DATA 3 E1432
.SH NAME
.nf
e1432_read_raw_data \- Read raw data from E1432 channel
e1432_read_float32_data \- Read scaled float data from E1432 channel
e1432_read_float64_data \- Read scaled float data from E1432 channel
.fi
.IX e1432_read_raw_data(3) 3
.IX e1432_read_float32_data(3) 3
.IX e1432_read_float64_data(3) 3
.SH SYNOPSIS
.cS
SHORTSIZ16 e1432_read_raw_data(E1432ID hw, SHORTSIZ16 ID,
                               SHORTSIZ16 which, void *buffer,
                               LONGSIZ32 size,
                               struct e1432_trailer *trailer,
                               LONGSIZ32 *actualCount)
SHORTSIZ16 e1432_read_float32_data(E1432ID hw, SHORTSIZ16 ID,
                                   SHORTSIZ16 which, FLOATSIZ32 *buffer,
                                   LONGSIZ32 size,
                                   struct e1432_trailer *trailer,
                                   LONGSIZ32 *actualCount)
SHORTSIZ16 e1432_read_float64_data(E1432ID hw, SHORTSIZ16 ID,
                                   SHORTSIZ16 which, FLOATSIZ64 *buffer,
                                   LONGSIZ32 size,
                                   struct e1432_trailer *trailer,
                                   LONGSIZ32 *actualCount)
.cE
.SH DESCRIPTION
\fIe1432_read_raw_data\fR returns a block of raw, \fIUN\fR-scaled
data. \fIbuffer\fR should be either a pointer to SHORTSIZ16,
LONGSIZ32, or FLOATSIZ32, depending upon the setting of the data size
(see \fIe1432_set_data_size\fR).

\fIe1432_read_float32_data\fR returns a block of 32 bit floating point
data.  The data is properly scaled to volts (or picoCoulombs if the
input channel is in charge mode).

\fIe1432_read_float64_data\fR returns a block of 64 bit floating point
data.  The data is properly scaled to volts (or picoCoulombs if the
input channel is in charge mode).

\fIe1432_read_raw_data\fR, \fIe1432_read_float32_data\fR and
\fIe1432_read_float64_data\fR can be called with either a group ID or
a channel ID.  If called with a group ID the buffer must be large
enough to hold all data from all channels in the group.  These
functions may return \fBERR1432_BUS_ERROR\fR if there is no data ready, so
use \fIe1432_block_available\fR to determine data readiness before
calling a read data function.  These functions will attempt to read
one blocksize worth of data as set by \fIe1432_set_blocksize\fR.

If channel IDs are used, any of these functions has to be called as
many times as there are active channels in the group for which the
data acquisition has just been performed.  Also, the channels MUST be
called in order of the channel list used to create the group.  The
channel ID does not really specify which channel's data to read - it
just indicates which module to read from, and the module sends the
next active channel.  Each channel must be read completely before the
next channel data is available.  All these restrictions are dealt with
by using a group ID instead of channel ID.

These data transfers are performed using the VME bus.  If the data
port is set to Local Bus, there is no need to read data via VME, and
these functions should not be used at all.

If \fIe1432_set_append_status\fR has been used to turn on the status
trailer, then a trailer is read from the module after reading the
block of data.  There are two ways to get this trailer data.

One way is to have the trailer appended to the end of each data block.
If this is done, then each block of data will have a trailer of eight
32-bit words appended to it.  The data buffer must be large enough to
accomodate the additional data.  The \fIsize\fR that is passed to this
function should be either 8 or 16 larger, for each channel, than it
would otherwise be.  If the current data size (as selected by
\fIe1432_set_data_size\fR) is \fBE1432_DATA_SIZE_16\fR, then 16 should
be added to the size.  Otherwise, 8 should be added to the size.  This
will ensure that the correct amount of data is read after each data
block.  The reason that the number varies is that the trailer
information is always in the same format, regardless of the current
data size setting.

The other way to get trailer data is to use the \fItrailer\fR
parameter.  If this is done, then the \fIsize\fR should NOT try to
account for the additional trailer data.  The \fItrailer\fR parameter
should point to an array of \fIe1432_trailer\fR structures, one for
each channel whose data will be read by this function.

\fIhw\fR must be the result of a successful call to
\fIe1432_assign_channel_numbers\fR, and specifies the group of
hardware to talk to.

\fIID\fR is the ID of a group or single channel.

\fIwhich\fR specifies what type of data to read.  
\fBE1432_TIME_DATA\fR causes time data to be read.

\fBE1432_FREQ_DATA\fR causes the results of an FFT of the time data to be read.

\fBE1432_RESAMP_DATA\fR causes resampled time data to be read.  For this data to
be available, the resampling calculation must be enabled by 
\fRe1432_set_calc_data\fR.

\fBE1432_OCTAVE_DATA\fR causes Octave date to be read.
For this data to be available, Octave measurements must be turned on
vi \fIe1432_set_octave_mode\fR.
\fBE1432_OCTAVE_DATA\fR is not valid for \fIe1432_read_raw_data\fR calls.
Octave data is in mean-squared form.
A square root must be taken to make it RMS.

\fBE1432_ORDER_DATA\fR causes the results of an FFT of the resampled time data 
(order data) to be read.  For this data to be available, the order 
calculation must be enabled by \fRe1432_set_calc_data\fR.

\fBNOTE:\fR The frequency data and order data are normally sent up as
complex data, real and imaginary pairs for each point.  Since the FFT
is a Real Valued Transform (RVT) on \fIblocksize\fR points of input
time data (or resampled time data in the case of order calculations),
the result normally would have one extra point in it
(\fIblocksize\fR/2 + 1), called the Fs/2 point which is necessary if
an inverse FFT is to be done in the host.  To save buffer space in the
E1432, the real part of the Fs/2 point is put into the imaginary part
of the DC frequency bin (first point in the block).  This is possible
because the imaginary parts of the DC point the Fs/2 point are zero.
The result of this packing is \fIblocksize\fR/2 complex pairs, or
\fIblocksize\fR points.  When one of the averaging modes is turned on
with \fIe1432_set_avg_mode\fR that cause only magnitude squared data
to be passed up, the resulting number of points is \fIblocksize\fR/2.
The Fs/2 information is lost with this type of averaging.

\fIbuffer\fR is a pointer to the array for returned data. 

\fIsize\fR is the size, in data points, of \fIbuffer\fR.  If \fIsize\fR
is less than the block size set with \fIe1432_set_blocksize\fR, some channel
data will be left on the E1432 and will corrupt future reads.

\fBNote:\fR always make this size less than or equal to the actual allocated
memory for \fIbuffer\fR or the function may overrun your \fIbuffer\fR.

\fItrailer\fR is a pointer to a structure of type \fIstruct
e1432_trailer\fR.  This parameter is ignored unless append status is
on (see \fIe1432_set_append_status\fR).  If append status is on, and
if this parameter is non-NULL, and if the size is equal to the
\fIblocksize\fR as specified by \fIe1432_set_blocksize\fR, then the
\fItrailer\fR structure is filled in with trailer data.  If the
\fIID\fR is a group ID, then \fItrailer\fR must point to an array of
structures, one for each channel in the group.

\fIactualCount\fR is a pointer to a long integer.  It is set to the
actual number of data points transferred into \fIbuffer\fR.  It will
always be less than or equal to \fIsize\fR.

.ne 8
.TS
box center;
c s s
c | c | c
l | c | c.
Data Transfer Sizes
_
Function	Data size	Bytes per data point
=
e1432_read_raw_data	16	2
_
e1432_read_raw_data	32	4
_
e1432_read_float32_data	any	4
_
e1432_read_float64_data	any	8
.TE

Data size is set using \fIe1432_set_data_size\fR.
.SH "RESET VALUE"
Not applicable.
.SH "RETURN VALUE"
Return 0 if successful, a (negative) error number otherwise.
.SH "SEE ALSO"
.na
e1432_get_scale, e1432_set_append_status, e1432_set_data_size,
e1432_set_data_port
.ad
